Skip to main content

Git Workflow

This page covers the end-to-end workflow for authoring a new Crew Aid from a MIP and merging it into the DIP Gitlab.

note

This page assumes the Initial Setup from 262COS-GIT-SOP-002 has been completed - Git credentials saved, SSL verification disabled, and group access granted.

1. Create Your Working Branch​

note

Never work directly on main. Always create a personal branch for your edits.

cd /cvah/git/CREW_AIDS

# Verify origin points to the DIP Gitlab
git remote -v
# Expected: origin  https://gitlab/262-cos/CREW_AIDS

# Pull the latest main
git pull

# Create and switch to a personal branch
git branch <YOUR_USERNAME>-edits
git checkout <YOUR_USERNAME>-edits

# Publish the branch to DIP Gitlab
git push --set-upstream origin <YOUR_USERNAME>-edits

2. Verify the Dev Preview is Running​

The MIP runs a crewaid-dev service that hosts a live Docusaurus dev preview at http://localhost:3000. This service monitors the /cvah/git/CREW_AIDS folder and reflects changes to .md files automatically - no container management needed.

Verify the service is running before editing:

sudo systemctl status crewaid-dev

If it is not running, start it:

sudo systemctl start crewaid-dev

Navigate to http://localhost:3000 in a browser to see the live preview as you edit.

caution

Dev mode is more lenient than the production build - it will sometimes show a page with an error banner rather than crashing entirely. Do not assume a page is safe to commit just because dev mode showed it. Any error banner or broken link warning in dev mode means the page will fail the production CI build.

note

The Docusaurus search bar does not function in dev mode. This is expected.

3. Create the Document Structure​

Open VS Code against the CREW_AIDS repo:

code /cvah/git/CREW_AIDS

Using the VS Code file explorer, create the document folder inside the appropriate category folder following the naming standard from Document Standards:

CREW_AIDS/<CATEGORY_FOLDER>/
  <TYPE>-<SERIES> - <TITLE>/
    assets/
    _category_.json
    00_introduction.md
    01_<section>.md

Checklist before writing content:

  • Folder named correctly (<TYPE>-<SERIES> - <TITLE>)
  • _category_.json created with label and link.description
  • 00_introduction.md created with Revision History table and Purpose section
  • assets/ folder created (even if empty - add a .gitkeep file if no images yet)

4. Write and Preview Content​

Edit your .md files in VS Code. After saving each file, switch to the browser and verify the page renders correctly at http://localhost:3000.

Things to verify for each page:

  • Page loads without an error banner
  • All callout blocks (:::tip, etc.) render with the correct styling
  • All images display (not broken)
  • All internal links navigate to the correct page
  • Tables render with proper alignment
  • Code blocks have syntax highlighting

Review Authoring Guidelines and Rendering Pitfalls while writing.

5. Commit Your Changes​

Once the pages look correct in the dev preview, commit the changes. Use descriptive commit messages that explain what was added or changed.

cd /cvah/git/CREW_AIDS

# See what changed
git status

# Stage your new document folder
git add docs/<CATEGORY_FOLDER>/<TYPE>-<SERIES> - <TITLE>/

# Or stage everything
git add .

# Commit with a descriptive message
git commit -m "Add 262COS-<CATEGORY>-<TYPE>-<SERIES>: <TITLE>"
tip

Commit often and in small logical chunks. A commit per section or per significant change is better than one large commit at the end. Each commit message should make it clear what changed - reviewers at 262COS/DOK use commit history to understand what was done.

6. Push to DIP Gitlab​

git push origin <YOUR_USERNAME>-edits

7. Create a Merge Request​

  1. Log in to the DIP Gitlab instance
  2. Navigate to the 262-cos / CREW_AIDS project
  3. Click Merge Requests in the left sidebar
  4. Click New merge request
  5. Set Source branch to your personal branch (<YOUR_USERNAME>-edits)
  6. Set Target branch to main
  7. Click Compare branches and continue
  8. Fill in a title and description summarizing what was added or changed
  9. Assign a reviewer (Mission Element Lead or their designee)
  10. Click Create merge request
Merge Request Review Guidelines

The following are common reasons a merge request will be rejected and sent back for rework:

  • Missing or malformed _category_.json
  • Missing 00_introduction.md or missing Revision History table
  • Broken internal links (these will be caught by the CI pipeline automatically)
  • MDX parse errors (caught by CI pipeline)
  • Folder or file naming that does not follow the standard
  • Unnecessary deletion or renaming of pre-existing files
  • Large unrelated changes bundled into a single merge request

8. Post-Mission Export​

At the end of a mission, all modified repositories must be exported and prepared for transfer to 262COS/DOK for review and incorporation into the R2D2 Gitlab. See 262COS-GIT-SOP-003 - Post-Mission DIP Gitlab Export for procedures.

262COS/DOK will create a new branch on the online R2D2 Gitlab for each modified repository and review all changes before merging into main - completing the feedback loop into the next DIP build.